---
title: Spec - howl.signal
tags: spec
---
<div class="spec-group spec-group-1">

<h1 id="howl.signal">howl.signal</h1>

<h4 id=".all-contains-all-registered-signals">.all contains all registered signals</h4>

<pre class="highlight moonscript"><code><span class="n">signal</span><span class="p">.</span><span class="n">register</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'bar'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'bar'</span><span class="p">,</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">all</span><span class="p">.</span><span class="n">foo</span></code></pre>

<div class="spec-group spec-group-2">

<h2 id=".register(name,-options)">.register(name, options)</h2>

<h4 id="raises-an-error-if-mandatory-fields-are-missing">raises an error if mandatory fields are missing</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'description'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">register</span><span class="w"> </span><span class="s1">'foo'</span></code></pre>

</div>
<div class="spec-group spec-group-2">

<h2 id=".unregister(name)">.unregister(name)</h2>

<h4 id="unregisters-the-specified-signal">unregisters the specified signal</h4>

<pre class="highlight moonscript"><code><span class="n">signal</span><span class="p">.</span><span class="n">register</span><span class="w"> </span><span class="s1">'frob'</span><span class="p">,</span><span class="w"> </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'bar'</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">unregister</span><span class="w"> </span><span class="s1">'frob'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_nil</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">all</span><span class="p">.</span><span class="n">frob</span></code></pre>

</div>
<div class="spec-group spec-group-2">

<h3 id="(trying-to-use-a-non-registered-signal)">(trying to use a non-registered signal)</h3>

<h4 id="emit-raises-an-error">emit raises an error</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'none'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'none'</span></code></pre>


<h4 id="connect-raises-an-error">connect raises an error</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'none'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'none'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">true</span></code></pre>

</div>
<div class="spec-group spec-group-2">

<h3 id="(with-a-registered-signal)">(with a registered signal)</h3>

<pre class="highlight moonscript"><code><span class="n">before_each</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">register</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'bar'</span><span class="w">
</span><span class="n">after_each</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">unregister</span><span class="w"> </span><span class="s1">'foo'</span></code></pre>


<h4 id="allows-name-based-signals-to-be-broadcasted-to-any-number-of-handlers">allows name based signals to be broadcasted to any number of handlers</h4>

<pre class="highlight moonscript"><code><span class="n">handler1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">nil</span><span class="w">
</span><span class="n">handler2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">nil</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler1</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler2</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler1</span><span class="p">).</span><span class="n">was_called</span><span class="o">!</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler2</span><span class="p">).</span><span class="n">was_called</span><span class="o">!</span></code></pre>


<h4 id="allows-connecting-handlers-before-existing-handlers">allows connecting handlers before existing handlers</h4>

<pre class="highlight moonscript"><code><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">nil</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'first'</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="o">-&gt;</span><span class="w"> </span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">'second'</span><span class="p">),</span><span class="w"> </span><span class="mi">1</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="n">value</span><span class="p">,</span><span class="w"> </span><span class="s1">'first'</span></code></pre>


<h4 id="allows-disconnecting-handlers">allows disconnecting handlers</h4>

<pre class="highlight moonscript"><code><span class="n">handler</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">disconnect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler</span><span class="p">).</span><span class="n">was</span><span class="p">.</span><span class="n">not_called</span><span class="o">!</span></code></pre>

<div class="spec-group spec-group-3">

<h3 id=".emit">.emit</h3>

<h4 id="raises-an-error-when-called-with-more-than-two-parameters">raises an error when called with more than two parameters</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'parameter'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="mi">2</span></code></pre>


<h4 id="raises-an-error-when-the-second-parameter-is-not-a-table">raises an error when the second parameter is not a table</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'table'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span></code></pre>


<h4 id="returns-false-if-no-handlers-returned-true">returns false if no handlers returned true</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="s1">'this is fortunately not true'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span></code></pre>


<h4 id="invokes-all-handlers-in-their-own-coroutines">invokes all handlers in their own coroutines</h4>

<pre class="highlight moonscript"><code><span class="n">coros</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{}</span><span class="w">
</span><span class="n">coro_register</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">
  </span><span class="n">co</span><span class="p">,</span><span class="w"> </span><span class="n">main</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">coroutine.running</span><span class="o">!</span><span class="w">
  </span><span class="n">coros</span><span class="p">[</span><span class="n">co</span><span class="p">]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="w"> </span><span class="k">unless</span><span class="w"> </span><span class="n">main</span><span class="w">

</span><span class="n">handler1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="n">coro_register</span><span class="w">
</span><span class="n">handler2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="n">coro_register</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler1</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler2</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="o">#</span><span class="p">[</span><span class="n">v</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">_</span><span class="p">,</span><span class="w"> </span><span class="n">v</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="nb">pairs</span><span class="w"> </span><span class="n">coros</span><span class="p">]</span></code></pre>

<div class="spec-group spec-group-4">

<h3 id="(when-a-handler-returns-.abort)">(when a handler returns .abort)</h3>

<h4 id="skips-invoking-subsequent-handlers">skips invoking subsequent handlers</h4>

<pre class="highlight moonscript"><code><span class="n">handler2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">abort</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler2</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler2</span><span class="p">).</span><span class="n">was</span><span class="p">.</span><span class="n">not_called</span><span class="o">!</span></code></pre>


<h4 id="returns-.abort">returns .abort</h4>

<pre class="highlight moonscript"><code><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">abort</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">equals</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">abort</span><span class="p">,</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span></code></pre>

</div>
<div class="spec-group spec-group-4">

<h3 id="(when-a-handler-raises-an-error)">(when a handler raises an error)</h3>

<h4 id="logs-an-error-message">logs an error message</h4>

<pre class="highlight moonscript"><code><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="nb">error</span><span class="w"> </span><span class="s1">'BOOM'</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">match</span><span class="w"> </span><span class="n">log</span><span class="p">.</span><span class="n">last_error</span><span class="p">.</span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="s1">'BOOM'</span></code></pre>


<h4 id="continues-processing-subsequent-handlers">continues processing subsequent handlers</h4>

<pre class="highlight moonscript"><code><span class="n">handler2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="nb">error</span><span class="w"> </span><span class="s1">'BOOM'</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler2</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler2</span><span class="p">).</span><span class="n">was_called</span><span class="o">!</span></code></pre>

</div>
<div class="spec-group spec-group-4">

<h3 id="(when-a-handler-yields)">(when a handler yields)</h3>

<h4 id="continues-on-invoking-subsequent-handlers">continues on invoking subsequent handlers</h4>

<pre class="highlight moonscript"><code><span class="n">handler2</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">spy</span><span class="p">.</span><span class="n">new</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="nb">coroutine.yield</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="n">handler2</span><span class="w">
</span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">spy</span><span class="p">(</span><span class="n">handler2</span><span class="p">).</span><span class="n">was_called</span><span class="o">!</span></code></pre>


<h4 id="returns-false">returns false</h4>

<pre class="highlight moonscript"><code><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'foo'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="nb">coroutine.yield</span><span class="w"> </span><span class="kc">true</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">signal</span><span class="p">.</span><span class="n">emit</span><span class="w"> </span><span class="s1">'foo'</span></code></pre>

</div>
</div>
</div>
</div>
